package dataflowscheme.engine.core;

/**
 * An interface for entity which can be connected by wires. 
 * Therefore is can receive and send data or signal tokens. 
 * 
 * @author <a href="mailto:misiak7@gmail.com">Michal Antolik</a>
 *
 */
public interface IConnectableEntity {

	/**
	 * Register a connection in initialization phase (processed by Main thread) 
	 */
	public void addConnection(String portName, IConnectableEntity oppossiteEntity, String oppossitePortName);

	/**
	 * It handles receiving of data token. It is processed by Event Parser thread.
	 * If all tokens for particular input portSet were already received then
	 * it will invoke a new execution (or queue it if currently an execution 
	 * is processed)
	 * 
	 * @param data A java objects representing received data token
	 * @param portName A port name, for which data should be received
	 * 
	 * @return true if data was set to the port
	 */
	public boolean receiveData(Object data, String portName);
	
	/**
	 * It handles receiving of signal token. It is processed by Event Parser thread.
	 * If all tokens for particular input portSet were already received then
	 * it will invoke a new execution (or queue it if currently an execution 
	 * is processed)
	 * 
	 * @param portName A port name, for which signal should be received
	 * 
	 * @return true if signal was set to the port
	 */
	public boolean receiveSignal(String portName);
	
	/**
	 * It is processed by Event Parser thread and it will receive 
	 * feedback about:
	 * - freePort: token was released from opposite port therefore 
	 * 			   a token (data or signal) should be send again.
	 * 			   This event is sent only if previous data or signal 
	 * 			   event was discarded because opposite port was full
	 * - delivered_ok: a token in opposite port was delivered and 
	 * 				   saved in port, therefore it can be removed 
	 * 				   from produced data or signals 
	 * - cleanPEmanually: A CleanEvent is created when after execution when
	 * 					  there are not data or signals to send and
	 * 					  a clean action to allow a new execution should be done.
	 * 					  CleanEvent is created by one of an execution event parser
	 * 					  thread in this processing entity and it is processed here.
	 * 
	 *  @param event One of delivered_ok, freePort, cleanPEmanually
	 *  @param portName a name of port for which a feedback should be processed
	 */
	public void receiveResponse(EventMsg event, String portName);
	
	/**
	 * @return name of Task or Storage
	 */
	public String getName();
}
